Release 10.1A: OpenEdge Development:
Progress 4GL Reference

SUBSCRIBE statement

Creates a subscription to a Progress named event.

Note: Progress named events are completely different from the key function, mouse, widget, and direct manipulation events described in the "Events Reference" section. For more information on Progress named events, see OpenEdge Development: Progress 4GL Handbook .

Syntax

SUBSCRIBE [ PROCEDURE subscriber-handle ] [ TO ] event-name { IN publisher-handle | ANYWHERE } [ RUN-PROCEDURE local-internal-procedure ] [ NO-ERROR ]

PROCEDURE subscriber-handle

A procedure or handle representing the subscriber.

The PROCEDURE option lets one procedure create a subscription on behalf of another. For example, if you want procedure A to create a subscription on behalf of procedure B, set subscriber-handle to the procedure handle of B.

If the PROCEDURE option does not appear, Progress creates a subscription on behalf of THIS-PROCEDURE, the procedure that contains the SUBSCRIBE statement.

TO event-name

A quoted string or a character expression representing the name of the event.

IN publisher-handle

Subscribes to the named events published by publisher-handle.

If publisher-handle is not a valid procedure or widget handle at the time the SUBSCRIBE statement executes, Progress reports a run time error unless you specify the NO-ERROR option.

ANYWHERE

Subscribes to named events published within the OpenEdge session-regardless of the publisher.

RUN-PROCEDURE local-internal-procedure

A quoted string or character expression representing the name of an internal procedure that resides within the subscribing program. Progress runs local-internal-procedure when the named event occurs.

If the RUN-PROCEDURE option does not appear, when the named event occurs, Progress runs an internal procedure with the same name as the named event.

Note: The RUN-PROCEDURE option lets you create a subscription when the event name and the procedure name do not match, or when you must subscribe to two different events that have the same name.

When the named event occurs, Progress RUNs each subscriber’s local internal procedure, passing the parameters, if any, The order in which Progress notifies subscribers is undefined. Progress always performs this RUN with an implicit NO-ERROR, and logs errors to the ERROR-STATUS system handle.

NO-ERROR

Tells Progress not to report a run time error if publisher-handle or subscriber-handle is not a valid procedure handle, or if Progress cannot evaluate an event-name expression. Errors are still generated, however, and are stored in the ERROR-STATUS handle.

Example

For an example, see the reference entry for the PUBLISH statement in this manual.

Notes

Within the local internal procedure, you can get a handle to the publisher of the named event by using the SOURCE-PROCEDURE system handle. For more information on the SOURCE-PROCEDURE system handle, see its reference entry in this book.
If Progress detects a redundant SUBSCRIBE statement—that is, a SUBSCRIBE statement with the same event name, and either the same publisher handle or the same ANYWHERE option—Progress does not report an error.
If event-name is a string containing spaces or is otherwise not a standard Progress name, use one of the following techniques:
Use the RUN-PROCEDURE option to assign the local internal procedure a more conventional name.
When you define local-internal-procedure, put its name in quotes, as in the following example:

PROCEDURE "spaced event":

See also

PUBLISH statement, PUBLISHED-EVENTS attribute, UNSUBSCRIBE statement